/* Copyright 2007,2008,2009 John C. Gunther
 * 
 * Licensed under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License. You may obtain a copy of the License at:
 * 
 *  http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
 * either express or implied. See the License for the specific
 * language governing permissions and limitations under the
 * License.
 */
package com.googlecode.gchart.client;

/**
 * Defines the extra features that must be added to a <tt>Widget</tt>
 * before it can be used to generate hover feedback.  You can customize
 * a curve's hover feedback by passing a <tt>Widget</tt> that
 * implements this interface to the <tt>setHoverWidget</tt> method.
 * <p>
 *
 * For example, the chart below uses a <tt>HoverUpdateable Button</tt>
 * to both display each point's x,y position, and allow the user to
 * delete that point (This is Chart #18 in the Chart Gallery. As with
 * all of these example charts, you'll
 * need to add the chart to the <tt>RootPanel</tt> and then invoke
 * the <tt>update</tt> method, as shown in the typical GChart
 * boilerplate <a
 * href="package-summary.html#typicalgchartboilerplate">code snippet</a>
 * to get this example to actually work).
 * 
 *
 * {@code.sample
 * ../../../../../../gcharttestapp/src/com/googlecode/gchart/gcharttestapp/client/GChartExample18.java}
 *
 * <p>
 *
 * Here's what this chart looks like with the user hovering over the
 * point at <tt>(5, 10)</tt>, before they have deleted anything:
 *
 * 
 * <p>
 * 
 * <img
 * src="{@docRoot}/com/googlecode/gchart/client/doc-files/gchartexample18.png">
 *
 * <p>
 *
 * <i>Tip</i>: If you just need to generate custom HTML that varies
 * with the hovered over point, it's probably easier to use
 * a <tt>HoverParameterInterpreter</tt> rather than a
 * <tt>HoverUpdateable</tt> widget. 
 *
 *
 * @see GChart.Symbol#setHoverWidget setHoverWidget
 * @see GChart.Symbol#setHoverLocation setHoverLocation
 * @see GChart.Symbol#setHoverAnnotationSymbolType setHoverAnnotationSymbolType
 * @see GChart.Symbol#setHoverXShift setHoverXShift
 * @see GChart.Symbol#setHoverYShift setHoverYShift
 * @see HoverParameterInterpreter HoverParameterInterpreter
 *
 */ 

public interface HoverUpdateable {

   /**
    * Frees any resources that the <tt>hoverUpdate</tt> method may have
    * allocated when the user first hovered over the point,
    * thus returning the hoverWidget to a well-defined state:
    * ready to recieve the next <tt>hoverUpdate</tt>
    * without errors, memory leaks, etc.
    * <p>
    * 
    * You might think of this method an an "undo" for
    * this interface's <tt>hoverUpdate</tt> method.
    * 
    * <p>
    *
    * GChart calls this method whenever the mouse moves away
    * from a point it was previously hovering over (just before
    * it hides the hover annotation and removes the hover
    * selection feedback from that point).
    * 
    * <p>
    * 
    * For example, a hover widget that contains a nested
    * <tt>MenuBar</tt> might
    * need to call <tt>setVisible(false)</tt> on any opened submenus,
    * because programatically making the main menu invisible (which
    * GChart will do automatically when you move away from the point)
    * does <i>not</i>, as you might have expected, hide all opened
    * sub-menus. Another possible use for this method is to commit a
    * series of changes the user made via a form-like hover widget when
    * the user implicitly "closes" the hover widget by moving the mouse
    * away from the point (when it makes sense, it's best to commit such changes
    * on-the-fly, to avoid the potential for lost work).
    * <p>
    * 
    * Note that GChart automatically removes (when
    * <tt>optimizeFormMemory</tt> is true) or makes invisible (when it's
    * false) the DOM representation of the hover widget when the mouse
    * moves away from the hovered over point. So, all you need to worry
    * about is cleaning up any artifacts generated by this widget's
    * <tt>hoverUpdate</tt> method.
    * <p>
    *
    * 
    * <i>Tip</i>: Most hover widgets, such as those that simply display
    * information about the hovered over point, don't have anything
    * that needs to be cleaned up, and thus can just use a do-nothing
    * <tt>hoverCleanup</tt> method: 
    * <p>
    *
    * <pre>
    *   public void hoverCleanup(Curve.Point hoveredAwayFrom) {}
    * </pre>
    *
    * @param hoveredAwayFrom the previously hovered over point that the
    *     user has just moved the mouse away from (and thus is no
    *     longer hovering over).
    *   
    * @see #hoverUpdate hoverUpdate
    * 
    */
   public void hoverCleanup(GChart.Curve.Point hoveredAwayFrom);

  /** Updates this widget so that it displays appropriate
      information about the given point.
      
      <p>
      
      GChart will call this method, as needed, to assure that the hover
      widget always displays information about the point that the user
      is currently "touching" with the mouse (the "hovered over" point).
      In particular, GChart calls <tt>hoverUpdate</tt> when the mouse
      first hovers over a point, but it won't call it again if you move
      the mouse in a way that keeps it hovering over that same point.
      
      <p>

      Note that whenever a point's hover annotation (e.g. hover widget)
      becomes visible, the hit test region for that point is in effect
      extended to include the rectangular box associated with its hover
      annotation. This policy creates a "sticky open" feel to hover
      widgets. Applications that allow the user to interact with the
      hover widget need to arrange for a "mousemove pathway" (by using
      methods such as <tt>setBrushSize</tt> and
      <tt>setHoverAnnotationSymbolType(ANCHOR_MOUSE)</tt> ) that allows
      the user to move the mouse into the hover widget without moving
      away from the hovered over point (which would otherwise dismiss
      the hover annotation before the user could interact with it).
      
      <p>
      

      This method only needs to concern itself with the content and/or
      size of the widget; GChart will position and change the visibility
      of the widget appropriately (as defined via the
      <tt>setHoverLocation</tt>, <tt>setHoverAnnotationSymbolType</tt>,
      <tt>setHoverXShift</tt> and <tt>setHoverYShift</tt> methods) as
      the user moves the mouse over different points on the chart.

      @param hoveredOver a reference to the point that the mouse
      has just begun hovering over. 
      <p>

      @see #hoverCleanup hoverCleanup
      @see GChart.Symbol#setHoverLocation setHoverLocation
      @see GChart.Symbol#setHoverAnnotationSymbolType setHoverAnnotationSymbolType
      @see GChart.Symbol#setHoverXShift setHoverXShift
      @see GChart.Symbol#setHoverYShift setHoverYShift
      @see GChart.Symbol#setBrushSize setBrushSize
      
  */

   public void hoverUpdate(GChart.Curve.Point hoveredOver);

   
}
